<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <title>Couchdbkit - Getting started</title>
    <!--[if IE]>

    <script>
        // allow IE to recognize HTMl5 elements
        document.createElement('section');
        document.createElement('article');
        document.createElement('aside');
        document.createElement('footer');
        document.createElement('header');
        document.createElement('nav');
        document.createElement('time');

    </script>
    <![endif]-->

    <link rel="stylesheet" href="/css/couchdbkit.css?20090615" type="text/css" media="screen, projection" />
    <link rel="stylesheet" href="/static/css/print.css?20090615" type="text/css" media="print" />
    <script type="text/javascript" src="/js/prettify.js"></script>
    
    <link rel="alternate" type="application/rss+xml" title="RSS 2.0" href="/feed.xml" />
    

    
        
</head>
<body onload="prettyPrint()">
    
    <div class="container">
        <header id="site_header">
            <h1><a href="/"><span>couchdbkit</span></a></h1>
            <ul id="main_nav">
                <li><a href="/">home</a></li>
                <li><a href="/blog/">news</a></li>
                <li><a href="/download.html">download</a></li>
                <li><a href="/docs/">documentation</a></li>
                <li><a href="/docs/api/">API</a></li>
            </ul>

        </header>
        
        
        
        
        <aside id="sidebar">
            <ul class="sidenav">
                <li><a href="/blog/">Latest news</a></li>
                <li><a href="/download.html">Download latest</a></li>
                <li><a href="/docs/gettingstarted.html">Getting started</a></li>
                <li><a href="/docs/faq.html">Frequently Asked Questions</a></li>
                <li><a href="/docs/about.html">About couchdbkit</a></li>
                <li><a href="/contact.html">Getting help with couchdbkit</a></li>
            </ul>
            <div class="info">
                <h3>Getting started</h3>
                <p>See the <a href="/download.html">download instructions</a> for information on getting couchdbkit, and read the <a href="/docs/gettingstarted.html">getting started</a> instructions to start programming CouchDB in your own application in less than 10 minutes.</p>
            </div>
            <div class="info">
                <h3>Get involved</h3>
                <ul>
                    <li><p><a href="http://webchat.freenode.net/?channels=couchdbkit">#couchdbkit IRC channel</a>: chat with other couchdbkit users</p></li>
                    <li><p><a href="http://github.com/benoitc/couchdbkit/issues">Ticket system</a>: report bugs and make feature requests</p></li>
                    <li><p><a href="http://groups.google.com/group/couchdbkit">Mailing-List</a>: The main list for help and follow changes.</p></li>
                </ul>
                        
            </div>
           
        </aside>
        
    
        
<section id="content">
    <article>
        <h1>Getting started</h1>
        	<p>This tutorial exposes key features of this library mainly through code<br />examples. For in-depth description of the modules, you&#8217;ll want to read <br />the <a href="/docs/api/">API</a>  documentation.</p>

	<p>If you have not installed couchdbkit yet, follow instructions on <a href="/download.html">download page</a> . Once you&#8217;ve done, you can write your first CouchDB document:</p>

	<p><pre class="code prettyprint">
 import datetime</p>

 from couchdbkit import *

 class Greeting(Document):
      author = StringProperty()
      content = StringProperty()
      date = DateTimeProperty()
</pre>

	<h2>Store the submitted Greetings</h2>

	<p>Here is the code to save a greet on `Greeting` database. We also see how to create a database.</p>

	<p><pre class="code prettyprint"></p>

 # server object
 server = Server()

 # create database
 db = server.get_or_create_db(&#8220;greeting&#8221;)

 # associate Greeting to the db
 Greeting.set_db(db)

 # create a new greet
 greet = Greeting(
     author=&#8220;Benoit&#8221;,
     content=&#8220;Welcome to couchdbkit world&#8221;,
     date=datetime.datetime.utcnow()
 )

 # save it 
 greet.save()
</pre>

	<p>Note: You can just use the <code>db.save</code> method to save any <code>Greeting</code> object.  </p>

	<p>Your document `greet` is now in the `greetings` db. Each document is saved with a `doc_type` field that allow you to find easily each kind of document with the views. By default `doc_type` is the name of the class.</p>

	<p>Now that you saved your document, you can update it:</p>

<pre class="code prettyprint">
 greet.author = u&#8220;Benoît Chesneau&#8221;
 greet.save()
</pre>

	<p>Here we updated the author name.</p>

	<h2>Dynamic properties</h2>

	<p>Mmm ok, but isn&#8217;t CouchDB storing documents schema less? Do you want to add a property ? Easy:</p>

<pre class="code prettyprint">
 greet.homepage = &#8220;http://www.e-engura.org&#8221;
 greet.save()
</pre>

	<p>Now you have just added an homepage property to the document.</p>

	<h3>Get all greetings</h3>

	<p>You first have to create a view and save it in the db. We will call it `greeting/all`. To do this we will use the loader system of couchdbkit that allows you to send views to couchdb.</p>

	<p>Let&#8217;s create a folder that contains the design doc, and then the folder for the view. On unix :</p>

<pre class="code prettyprint">
 mkdir -p ~/Work/couchdbkit/example/_design/greeting/views/all
</pre>

	<p>In this folder we edit a file `map.js`:</p>

<pre class="code prettyprint">
 function(doc) { 
   if (doc.doc_type == &#8220;Greeting&#8221;) 
    emit(doc._id, doc); 
 }
</pre>

	<p>On <a href="http://macromates.com">Textmate</a>, you have:</p>

	<p><img src="/images/gettingstarted.png" title="couchdbkit textmate screen" alt="couchdbkit textmate screen" /></p>

	<p>A system will be provided to manage view creation and other things. As some noticed, this system works like <a href="http://github.com/couchapp/couchapp/tree/">couchapp</a>.</p>

	<p>Then we use `FileSystemDocsLoader` object to send the design document to CouchDB:</p>

	<p><pre class="code prettyprint">
 from couchdbkit.designer import push</p>

 push(&#8217;/path/to/example/_design/greeting&#8217;, db)
</pre>

	<p>The design doc is now in the `greetings` database and you can get all greets :</p>

<pre class="code prettyprint">
 greets = Greeting.view('greeting/all&#8217;)
</pre>
    </article>
</section>

        
        <footer id="bottom">
            <p class="copyright">2008-2012 &copy; <a href="http://benoitc.org">Benoît Chesneau</a> - Some rights reserved.</p>
            <div id="cc"><a rel="license" href="http://creativecommons.org/licenses/by/2.0/fr/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by/2.0/fr/80x15.png" /></a> This <span xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/InteractiveResource" rel="dc:type">website</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/2.0/fr/">Creative Commons Attribution 2.0 France License</a>.</div>
            <p>Hosted on <a href="http://github.com/">GitHub</a></p>
        </footer>
        
    </div>

    
    
    
</body>
</html>